Would it be possible change this list so only these are documented? https://github.com/ESMValGroup/ESMValTool/tree/main/doc/sphinx/source/api

yeh lemme add all those to the list that way then

it works nicely! Less than two minutes to run, but it throws 100+ warnings, see https://readthedocs.org/projects/esmvaltool/builds/24660091/ - I think I know what's going on in here - there are two types of warnings:

• a lot coming from autodoc which I should turn it off completely
• another lot coming from autoapi docs dir sitting inside our source so it's kicking its own butt since the autoapi docs are not included in any docs

hey Bouwe, any ideas how to fix these warnings? https://readthedocs.org/projects/esmvaltool/builds/24661254/ - I've done everything I could think of, and a tap dance on top of it too - autodoc keeps wanting to import modules, even though I added ESMValTool and esmvaltool to the Python path (that's just not how things should be done, but that's what the Sphinx folks say we should do), and the blithering autoapi keeps creating that index.rst even if I told it no with autoapi_generate_api_docs = False (see https://sphinx-autoapi.readthedocs.io/en/latest/how_to.html). I am stuck, and am gonna leave it for now 😁

I think I fixed the build in f07c760, but it is not pretty. Somehow I cannot get autoapi to respect what is in __all__ (see here). At least in part that seems to be because it also searches for executable scripts and documents those and those appear to be scattered throughout the code base. Maybe if we clean that up things will work better?

We would still need to move the documentation from the now deleted doc/sphinx/source/api directory to the Python modules and do some further polishing before this is ready.

that's a serious bit of progress - from 126 to 7 warnings, bud 🍺 But what do you mean moving the docs to the Python modules, as in create the docs in the same place where the source code lives? Lemme see about restricting Autoapi to not look for executables, that should have a configuration solution

It's not executable scripts after all, it is missing __init__.py files that generate all the extra packages. Let me try to add some.

ahaa! That's me completely unawares - it's great you figured that out otherwise it'd have taken me until 2027 to 😁 So I figured out the tests issue and now I think I just need to add Katja's testkw to the ignored list too

But what do you mean moving the docs to the Python modules, as in create the docs in the same place where the source code lives?

Copy the text from the deleted .rst files to the module docstrings